---
sidebar_label: Use variables / aliases / fragments / directives
sidebar_position: 10
description: Use variables, aliases, fragments and directives in Hasura queries
keywords:
  - hasura
  - docs
  - postgres
  - query
  - variable
  - alias
  - fragment
  - directive
---

import GraphiQLIDE from '@site/src/components/GraphiQLIDE';

# Use Variables / Aliases / Fragments / Directives in Queries

## Using variables

In order to make a query re-usable, it can be made dynamic by using
variables.

**Example:** Fetch an author by their `author_id`:

<GraphiQLIDE
  query={`query getArticles($author_id: Int!, $title: String!) {
  articles(
    where: { author_id: { _eq: $author_id }, title: { _ilike: $title } }
  ) {
    id
    title
  }
}`}
response={`{
  "data": {
    "articles": [
      {
        "id": 15,
        "title": "How to climb Mount Everest"
      },
      {
        "id": 6,
        "title": "How to be successful on broadway"
      }
    ]
  }
}`}
variables={`{
  "author_id": 1,
  "title": "%How to%"
}`}
/>

## Using aliases

Aliases can be used to return objects with a different name than their
field name. This is especially useful while fetching the same type of
objects with different arguments in the same query.

**Example:** First, fetch all articles. Second, fetch the two top-rated
articles. Third, fetch the worst-rated article:

<GraphiQLIDE
  query={`query getArticles {
  articles {
    title
    rating
  }
  topTwoArticles: articles(
    order_by: {rating: desc},
    limit: 2
  ) {
    title
    rating
  }
  worstArticle: articles(
    order_by: {rating: asc},
    limit: 1
  ) {
    title
    rating
  }
}`}
response={`{
  "data": {
    "articles": [
      {
        "title": "How to climb Mount Everest",
        "rating": 4
      },
      {
        "title": "How to be successful on broadway",
        "rating": 20
      },
      {
        "title": "How to make fajitas",
        "rating": 6
      }
    ],
    "topTwoArticles": [
      {
        "title": "How to be successful on broadway",
        "rating": 20
      },
      {
        "title": "How to make fajitas",
        "rating": 6
      }
    ],
    "worstArticle": [
      {
        "title": "How to climb Mount Everest",
        "rating": 4
      }
    ]
  }
}`}
/>

## Using fragments

Sometimes, queries can get long and confusing. A fragment is a set of
fields with any chosen name. This fragment can then be used to represent
the defined set.

**Example:** Creating a fragment for a set of `article` fields (`id` and
`title`) and using it in a query:

<GraphiQLIDE
  query={`fragment articleFields on articles {
  id
  title
}
query getArticles {
  articles {
    ...articleFields
  }
  topTwoArticles: articles(
    order_by: {rating: desc},
    limit: 2
  ) {
    ...articleFields
  }
}`}
response={`{
  "data": {
    "articles": [
      {
        "id": 3,
        "title": "How to make fajitas"
      },
      {
        "id": 15,
        "title": "How to climb Mount Everest"
      },
      {
        "id": 6,
        "title": "How to be successful on broadway"
      }
    ],
    "topTwoArticles": [
      {
        "id": 6,
        "title": "How to be successful on broadway"
      },
      {
        "id": 3,
        "title": "How to make fajitas"
      }
    ]
  }
}`}
/>

## Using directives

Directives make it possible to include or skip a field based on a
boolean expression passed as a query variable.

### @include(if: Boolean)

With `@include(if: Boolean)`, it is possible to include a field in the
query result based on a Boolean expression.

**Example:** The query result includes the field `publisher`, as
`$with_publisher` is set to `true`:

<GraphiQLIDE
  query={`query getArticles($with_publisher: Boolean!) {
  articles {
    title
    publisher @include(if: $with_publisher)
  }
}`}
response={`{
  "data": {
    "articles": [
      {
        "title": "How to climb Mount Everest",
        "publisher": "Mountain World"
      },
      {
        "title": "How to be successful on broadway",
        "publisher": "Broadway World"
      },
      {
        "title": "How to make fajitas",
        "publisher": "Fajita World"
      }
    ]
  }
}`}
variables={`{
  "with_publisher": true
}`}
/>

**Example:** The query result doesn't include the field `publisher`, as
`$with_publisher` is set to `false`:

<GraphiQLIDE
  query={`query getArticles($with_publisher: Boolean!) {
  articles {
    title
    publisher @include(if: $with_publisher)
  }
}`}
response={`{
  "data": {
    "articles": [
      {
        "title": "How to climb Mount Everest"
      },
      {
        "title": "How to be successful on broadway"
      },
      {
        "title": "How to make fajitas"
      }
    ]
  }
}`}
variables={`{
  "with_publisher": false
}`}
/>

### @skip(if: Boolean)

With `@skip(if: Boolean)`, it is possible to exclude (skip) a field in
the query result based on a Boolean expression.

**Example:** The query result doesn't include the field `publisher`, as
`$with_publisher` is set to `true`:

<GraphiQLIDE
  query={`query getArticles($with_publisher: Boolean!) {
  articles {
    title
    publisher @skip(if: $with_publisher)
  }
}`}
response={`{
  "data": {
    "articles": [
      {
        "title": "How to climb Mount Everest"
      },
      {
        "title": "How to be successful on broadway"
      },
      {
        "title": "How to make fajitas"
      }
    ]
  }
}`}
variables={`{
  "with_publisher": true
}`}
/>

**Example:** The query result includes the field `publisher`, as
`$with_publisher` is set to `false`:

<GraphiQLIDE
  query={`query getArticles($with_publisher: Boolean!) {
  articles {
    title
    publisher @skip(if: $with_publisher)
  }
}`}
response={`{
  "data": {
    "articles": [
      {
        "title": "How to climb Mount Everest",
        "publisher": "Mountain World"
      },
      {
        "title": "How to be successful on broadway",
        "publisher": "Broadway World"
      },
      {
        "title": "How to make fajitas",
        "publisher": "Fajita World"
      }
    ]
  }
}`}
variables={`{
  "with_publisher": false
}`}
/>
